Using the pan manipulator

Use the pan manipulator to enable users to move nodes in your Kanzi application. For example, you can use the pan manipulator to enable users to move a map. See Enabling the pan gesture for a node.

Use the Pan Manipulator triggers to react to the pan gesture. For example, you can set the appearance of a node when the user pans that node. See Using the Pan Manipulator triggers.

The pan manipulator is one of the input manipulators you can use to add gesture recognition to nodes in your Kanzi application. You can assign the input manipulators through the Kanzi Engine API. See Using input manipulators.

Learn how to use the pan manipulator by completing a tutorial. See Tutorial: Pan, zoom, tap.

Enabling the pan gesture for a node

To enable the pan gesture for a node:

1. In Kanzi Studio create a project using the Application template.
   
2. In the Project create a node for which you want to enable the pan gesture.
   For example, create an Image node and name it PanNode.
   
   
3. In the Project select the node you created in the previous step, in the Properties add the Hit Testable property, and set it to enabled.
   When you enable this property you enable the user to pick a node.
   By default hit testing is enabled for the Button, List Box Item Container, Scroll View, and Slider nodes. See Defining which node receives user input.
   
4. In the Project press Alt and right-click the node you created and select Alias.
   Kanzi Studio creates an alias pointing to the node from which you created the alias and adds it to the resource dictionary of its nearest ancestor node that contains a resource dictionary.
   Access alias target nodes using the # sign followed by the name of the alias.
   
5. Select File > Export > Export KZB.
   Kanzi Studio creates the kzb file and configuration files from your Kanzi Studio project. Kanzi Studio stores the exported files in the <ProjectName>/Application/bin directory or the location you specify in the Binary Export Directory property in Project > Properties. The kzb file contains all nodes and resources from your Kanzi Studio project, except the resources you mark in a localization table as locale packs.
   When you run your Kanzi application from Visual Studio, your application loads the kzb file and configuration files.
   
6. In Visual Studio open the solution stored in <ProjectName>/Application/configs/platforms/win32 and in the file which implements the logic of your application create and configure the pan manipulator:
   1. Define the handlers for the pan messages.
      For example, after the public section of the class which implements the logic of your application add:
      

      private:
      
          // Define the handler for the PanManipulator::StartedMessage message from 2D nodes
          // that have an input manipulator which generates pan messages.
          // This handler prepares a 2D node for a pan gesture.
          void onPanStarted(PanManipulator::StartedMessageArguments& messageArguments)
          {
              // Get from the message arguments the node that the user pans.
              Node2DSharedPtr node2d = dynamic_pointer_cast<Node2D>(messageArguments.getSource());
      
              if (!node2d)
              {
                  return;
              }
      
              // When starting a pan gesture on the node, bring the node to front.
              node2d->moveToFront();
          }
      
          // Define the handler for the PanManipulator::MovedMessage message from 2D nodes
          // that have an input manipulator which generates pan messages.
          // This handler translates a 2D node by the amount of the pan gesture.
          void onPanMoved(PanManipulator::MovedMessageArguments& messageArguments)
          {
              // Get from the message arguments the node that the user pans.
              Node2DSharedPtr node2d = dynamic_pointer_cast<Node2D>(messageArguments.getSource());
      
              if (!node2d)
              {
                  return;
              }
      
              // Get the distance in pixels that the pan has progressed
              // since the last message in the pan gesture sequence.
              Vector2 translationDelta = messageArguments.getDelta();
      
              // Get the Render Transformation property of the node.
              SRTValue2D nodeTransform = node2d->getRenderTransformation();
      
              // Get the size of the node.
              Vector2 nodeSize = node2d->getActualSize();
      
              // Get the current translation of the node.
              Vector2 translation = nodeTransform.getTranslation();
      
              // Apply the translation from the pan message.
              Vector2 translationTarget = translation - translationDelta;
      
              // Set the new translation.
              nodeTransform.setTranslation(translationTarget);
      
              // Apply the new transform to the node.
              node2d->setRenderTransformation(nodeTransform);
          }

   2. In the onProjectLoaded() function create a PanManipulator manipulator and subscribe to its messages.
      For example, add:

          virtual void onProjectLoaded() KZ_OVERRIDE
          {
              ScreenSharedPtr screen = getScreen();
              Domain* domain = getDomain();
      
              // Get the PanNode using its alias.
              NodeSharedPtr panNode = screen->lookupNode<Node>("#PanNode");
      
              // Create an input manipulator that generates pan messages.
              PanManipulatorSharedPtr panManipulator = PanManipulator::create(domain);
      
              // Set the threshold in pixels on the horizontal and vertical axis that the finger
              // or mouse has to move before the input manipulator recognizes the pan gesture.
              panManipulator->setRecognitionThreshold(Vector2(10.0f, 10.0f));
       
              // Add the input manipulator to the PanNode.
              panNode->addInputManipulator(panManipulator);
      
              // Subscribe to the PanManipulator::StartedMessage message at the PanNode.
              // The PanManipulator generates this message when the user clicks or touches the attached node.
              panNode->addMessageHandler(PanManipulator::StartedMessage, bind(&MyProject::onPanStarted, this, placeholders::_1));
      
              // Subscribe to the PanManipulator::MovedMessage message at the PanNode.
              // The PanManipulator generates this message initially when the user moves their finger or mouse
              // on the horizontal or vertical axis more than the recognition threshold, and after that
              // when the finger or mouse has moved between updates.
              panNode->addMessageHandler(PanManipulator::MovedMessage, bind(&MyProject::onPanMoved, this, placeholders::_1));
          }

7. Build and run your application. See Deploying Kanzi applications.
   In the application click and drag or tap and drag the node for which you enabled the pan gesture.

Using the Pan Manipulator triggers

Use the Pan Manipulator triggers to react to the pan gesture. For example, you can set the appearance of a node when the user pans that node.

The Pan Manipulator has these triggers:

• Pan Started trigger is set off when the user clicks or taps a node but does not yet drag that node.
• Pan Moved trigger is set off when the user moves a node with the pan gesture.
• Pan Finished trigger is set off when the user ends the pan gesture by lifting their finger or releasing the mouse button.

To use the Pan Manipulator triggers:

1. Enable the pan gesture for a node. See Enabling the pan gesture for a node.
2. Define the behavior that you want to set with the Pan Manipulator triggers.
   For example, create a state manager where you define the states which set the appearance of a node when the Pan Started, Pan Moved, and Pan Finished triggers are set off. See Creating a state manager.
3. Add and configure a Pan Manipulator trigger:
   1. In the Project select the node to which you want to add the trigger, and in the Node Components > Triggers section add one of the Pan Manipulator triggers.
      For example, in the Project select the node for which you enabled the pan gesture and in the Node Components add the Pan Started trigger.
      
   2. In the trigger you created in the previous step click Trigger Settings and in the Trigger Settings Editor disable the Set Message Handled property.
      When you disable the Set Message Handled property, this trigger intercepts the message, but does not stop it. This way you let the input manipulator handle the message.
      
   3. In the trigger you created, in the Add dropdown menu select an action and configure it.
      For example, select the Go to State action, and in the action settings set:
      • Item to the node for which you enabled the pan gesture
      • State to the state which sets the appearance of the node when the Pan Started trigger is set off
      
4. Repeat the previous step to add and configure more Pan Manipulator triggers.
   For example, add the Pan Moved and Pan Finished triggers. In the Go to State action of each trigger set State to the state which sets the appearance of the node when that trigger is set off.
5. Select File > Export > Export KZB.
   
6. Build and run your application. See Deploying Kanzi applications.
   In the application click and drag or tap and drag the node for which you enabled the pan gesture.

Using the pan manipulator in the API

For details, see the PanManipulator class in the API reference.

See also

Tutorial: Pan, zoom, tap

Handling user input

Using the pinch manipulator

Using the Scroll View nodes

Deploying Kanzi applications

Using triggers

Open topic with navigation